Creating Variable Functions
This document describes how to create variable functions. Also see:
Class Inheritance
You can create your own functions for any IDL data type (except structures and objects). The variable classes have the following inheritance structure:
You can create new functions on any of the IDL Data Type classes (such as IDL_Byte) or any of the superclasses (IDL_Integer, IDL_Number, and IDL_Variable).
When you create a new function and add it to IDL's path, that function will immediately become available to all variables of that data type within your IDL session. In addition, if your function is on one of the superclasses, then the function will become available to all subclasses. For example:
- If you create a function called
IDL_Float::Fraction
, the::Fraction
function will be available on all variables of type FLOAT. - If you create a function called
IDL_Number::IsWhole
, the::IsWhole
function will be available on all IDL numeric data types. - If you create a function called
IDL_Variable::Save
, the::Save
function will be available for all IDL variables (except structures and objects).
Note: All variable methods must be functions, not procedures.
Arguments and Keywords
Your variable function should have the following signature:
function Class::MyFunction, variable [, arg2, arg3, ...] [KEYWORD=keyword, ...]
compile_opt IDL2, STATIC
...
return, result
end
The first argument is always set equal to the variable that was used to invoke the function. You can have any number of other arguments and keywords.
Be sure to use "compile_opt STATIC" to mark your function as a static method.
Example: IDL_Variable Function
We will create a function called IDL_Variable::Serialize
that will convert any IDL variable (except structures and objects) to a JSON string and optionally save the string to a file. Create the following code and save it to a file called "idl_variable__serialize.pro
":
function IDL_Variable::Serialize, variable, FILE=file
; Use STATIC to mark this as a static method
compile_opt IDL2, STATIC
ON_ERROR, 2
; Convert the variable to a JSON string.
; If type is a pointer, then dereference.
result = JSON_SERIALIZE((variable.tname eq 'POINTER') ? $
*variable : variable)
; Optionally save the JSON to a file.
if (ISA(file)) then begin
OPENW, lun, file, /GET_LUN
PRINTF, lun, result
FREE_LUN, lun
endif
return, result
end
For example:
IDL> data = FINDGEN(3,2)
IDL> HELP, data.Serialize()
IDL> PRINT, data.Serialize()
[[0.0,1.0,2.0],[3.0,4.0,5.0]]
IDL prints:
<Expression> STRING = '[[0.0,1.0,2.0],[3.0,4.0,5.0]]'
[[0.0,1.0,2.0],[3.0,4.0,5.0]]
Using the same function with a string array for input:
IDL> arr = ['abc', 'def', 'ghi', 'idl']
IDL> void = arr.Serialize(FILE='mydata.json')
Example: IDL_String Function
Now we will create a function that will take a JSON string and convert it back to an IDL variable. Create the following code and save it to a file called "idl_string__parsejson.pro
":
function IDL_String::ParseJSON, json
; Use STATIC to mark this as a static method
compile_opt IDL2, STATIC
ON_ERROR, 2
result = JSON_PARSE(json, /TOARRAY, /TOSTRUCT)
return, result
end
Here, we take a valid JSON string and call the function:
IDL> json = '{"key1":0.0, "key2":[1,2,3], "key3":true}'
IDL> result = json.ParseJSON()
IDL> help, result
IDL prints:
** Structure <107234a0>, 3 tags, length=40, data length=33, refs=1:
KEY1 DOUBLE 0.00000000
KEY2 LONG64 Array[3]
KEY3 BOOLEAN true (1)